<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Filling functions &mdash; GSLab Make 2.0.0 documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/underscore.js"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/sphinx_highlight.js"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="tablefill" href="api/tablefill/gslab_make.tablefill.tablefill.html" />
    <link rel="prev" title="zip_dir" href="api/modify_dir/gslab_make.modify_dir.zip_dir.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            GSLab Make
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="specifying_paths.html">Specifying paths</a></li>
<li class="toctree-l1"><a class="reference internal" href="general_logging.html">General logging functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="sourcing.html">Sourcing functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="source_logging.html">Source logging functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="program.html">Program functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="utility.html">Utility functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="repository.html">Repository functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="directory.html">Directory functions</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Filling functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="api/tablefill/gslab_make.tablefill.tablefill.html">tablefill</a></li>
</ul>
</li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">GSLab Make</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Filling functions</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/pages/filling.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="filling-functions">
<h1>Filling functions<a class="headerlink" href="#filling-functions" title="Permalink to this heading"></a></h1>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">gslab_make</span></code> library provides functions fill in tables and text in LyX/LaTeX documents.</p>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">tablefill</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">inputs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">template</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">null</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'.'</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Fills tables in document <code class="docutils literal notranslate"><span class="pre">template</span></code> using files in list <code class="docutils literal notranslate"><span class="pre">inputs</span></code>.
Writes filled document to file <code class="docutils literal notranslate"><span class="pre">output</span></code>.
Null characters in <code class="docutils literal notranslate"><span class="pre">inputs</span></code> are replaced with value <code class="docutils literal notranslate"><span class="pre">null</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>inputs</strong> (<em>list</em>) – Input or list of inputs to fill into template.</p></li>
<li><p><strong>template</strong> (<em>str</em>) – Path of template to fill.</p></li>
<li><p><strong>output</strong> (<em>str</em>) – Path of output.</p></li>
<li><p><strong>null</strong> (<em>str</em>) – Value to replace null characters (i.e., <code class="docutils literal notranslate"><span class="pre">''</span></code>, <code class="docutils literal notranslate"><span class="pre">'.'</span></code>, <code class="docutils literal notranslate"><span class="pre">'NA'</span></code>). Defaults to <code class="docutils literal notranslate"><span class="pre">'.'</span></code>.</p></li>
</ul>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
<p class="rubric">Example</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>#################################################################
#  tablefill_readme.txt - Help/Documentation for tablefill.py
#################################################################

Description:
tablefill.py is a Python module designed to fill LyX/Tex tables with output
from text files (usually output from Stata or Matlab).

Usage:
Tablefill takes as input a LyX (or Tex) file containing empty tables (the template
file) and text files containing data to be copied to  these tables (the
input  files), and produces a LyX (or Tex) file with filled tables (the output file).
For brevity, LyX will be used to denote LyX or Tex files throughout.

Tablefill must first be imported to make.py.  This is typically achieved
by including the following lines:

```
from gslab_fill.tablefill import tablefill
```

Once the module has been imported, the syntax used to call tablefill is
as follows:

```
tablefill(input = &#39;input_file(s)&#39;, template = &#39;template_file&#39;,
          output = &#39;output_file&#39;)
```

The argument &#39;template&#39; is the user written LyX file which contains the
tables to be filled in. The argument &#39;input&#39; is a list of the text files
containing the output to be copied to the LyX tables. If there are multiple
input text files, they are listed as: input = &#39;input_file_1 input_file_2&#39;.
The argument &#39;output&#39; is the name of the filled LyX file to be produced.
Note that this file is created by tablefill.py and should not be edited
manually by the user.

###########################
Input File Format:
###########################

The data needs to be tab-delimited rows of numbers (or characters),
preceeded by  `&lt;label&gt;`.  The &lt; and &gt; are mandatory. The numbers can be
arbitrarily long, can be negative, and can also be in scientific notation.

Examples:
----------

```
&lt;tab:Test&gt;
1   2   3
2   3   1
3   1   2
```

```
&lt;tab:FunnyMat&gt;
1   2   3   23  2
2   3
3   1   2   2
1
```
(The rows do not need to be of equal length.)

Completely blank (no tab) lines are ignored.
If a &quot;cell&quot; is merely &quot;.&quot; or &quot;[space]&quot;, then it is treated as completely
missing. That is, in the program:

```
&lt;tab:Test&gt;
1   2   3
2   .   1   3
3       1   2
```

is equivalent to:
```
&lt;tab:Test&gt;
1   2   3
2   1   3
3   1   2
```

This feature is useful as Stata outputs missing values in numerical
variables as &quot;.&quot;, and missing values in string variables as &quot;[space]&quot;.

................................
 Scientific Notation Notes:
................................
The scientific notation ihas to be of the form:
[numbers].[numbers]e(+/-)[numbers]

Examples:
```
23.2389e+23
-2.23e-2
-0.922e+3
```

###########################
Template LyX Format:
###########################

The LyX template file determines where the numbers from the input files are placed.

Every table in the template file (if it is to be filled) must appear within a float.
There must  be one, and only one, table object inside the float, and the table name
must include a label  object that corresponds to the label of the required table in
the input file.

Note that table names cannot be duplicated.  For a single template file, each table
to be filled must have a unique label, and there must be one, and only one, table with
that same label in the text files used as input. Having multiple tables with the
same name in the input files or in the template file will cause errors.

Note also that labels are NOT case-sensitive. That is, &lt;TAB:Table1&gt; is considered
 the same as `&lt;tab:table1&gt;`.

In the LyX tables, &quot;cells&quot; to be filled with entries from the input text files are
indicated by the following tags:

`&quot;###&quot;  (no quotes)`
or
`&quot;#[number][,]#&quot;  (no quotes)`

The first case will result in a literal substitution.  I.e. whatever is in the text
tables for that  cell will be copied over. The second case will convert the data
table&#39;s number (if in scientific notation) and will truncate this converted number
to [number] decimal places.  It will automatically round while doing so.

If a comma appears after the number (within #[number]#), then it will add commas
to the digits to the left of the decimal place.

Examples:
---------
```
2309.2093 + ### = 2309.2093
2309.2093 + #4# = 2309.2093
2309.2093 + #5# = 2309.20930
2309.2093 + #20# = 2309.20930000000000000000
2309.2093 + #3# = 2309.209
2309.2093 + #2# = 2309.21
2309.2093 + #0# = 2309
2309.2093 + #0,# = 2,309
```

```
-2.23e-2  + #2# = -0.0223 + #2# = -0.02
-2.23e-2  + #7# = -0.0223 + #7# = -0.0223000
-2.23e+10  + #7,# = -22300000000 + #7,# = -22,300,000,000.000000
```

Furthermore, only ###/#num# will be replaced, allowing you to put things around
###/#num# to alter the final output:

Examples:
--------

```
2309.2093 + (#2#) = (2309.21)
2309.2093 + #2#** = 2309.21**
2309.2093 + ab#2#cd = ab2309.21cd
```

If you are doing exact substitution, then you can use characters:

Examples:
---------
`abc + ### = abc`

................................
 Intentionally blank cells:
................................

If you would like to display a blank cell, you can use &quot;---&quot;:

Examples:
---------
```
--- + ### = ---
--- + #3# = ---
```

######################
# Example Combinations
#   Of input + template
######################

Example 1 (Simple)
----------
```
Input: &lt;tab:Test&gt;
1   2   3
2   1   3
3   1   2

Template: `&lt;tab:Test&gt; ` (pretend this is what you see in LyX)

### ### ###
### ### ###
### ### ###

Result:&lt;tab:Test&gt;
1   2   3
2   1   3
3   1   2
```

Example 2 (More Complicated)
----------
```
Input: &lt;tab:Test&gt;
1   .   3
2e-5    1   3.023
.   -1  2   3

Template: &lt;tab:Test&gt;  (pretend this is what you see in LyX)
(###)   2   ###
#3# ### #1#
NA  ### ### ###

Result:&lt;tab:Test&gt;
(1) 2   3
0.000   1   3.0
NA  -1  2   3
```

===================
====Important======
===================
By design, missings in input table and &quot;missings&quot; in template do not have to
line up.

Example 3 (LyX)
----------
```
Input: &lt;tab:Test&gt;
1   .   3
2e-5    .   3.023
.   -1  2

Template: &lt;tab:Test&gt;
### ### abc
abc #2# #3#
NA  ### ###

Result:&lt;tab:Test&gt;
1   3   abc
abc 0.00    3.023
NA  -1  2

Recall that to the program, the above input table is no different from:
1   3
2e-5    3.023
-1  2
```

It doesn&#39;t &quot;know&quot; where the numbers should be placed within a row, only what
the next number to place should be.

Similarly:

Example 4 (LyX)
----------
```
Input: &lt;tab:Test&gt;
1   1   2
1   1   3
2   -1  2

Template: &lt;tab:Test&gt;
### ### ###
abc abc abc
### #2# #3#
### ### ###

Result:&lt;tab:Test&gt;
1   1   2
abc abc abc
1   1.00    3.000
2   -1  2
```

If a row in the template has no substitutions, then it&#39;s not really a row from
the program&#39;s point of view.


######################
# Error Logging
######################

If an error occurs during the call to tablefill, it will be displayed in the
command window.  When make.py finishes, the user will be able to scroll up
through the output and examine any  error messages.  Error messages, which
include a description of the error type and a traceback to the line of code
where the error occured, can also be retuned as a string object using the
following syntax:

exitmessage = tablefill( input = &#39;input_file(s)&#39;, template = &#39;template_file&#39;,
                         output = &#39;output_file&#39; )

Lines can then be added to make.py to output this string to a log file using
standard Python and built in gslab_make commands.


######################
# Common Errors
######################

Common mistakes which can lead to errors include:

- Mismatch between the length of the LyX table and the corresponding text table.
If the LyX table has more entries to be filled than the text table has entries to
fill from, this will cause an error and the table will not be filled.

- Use of numerical tags (e.g. #1#) to fill non-numerical data.  This will cause
an error. Non-numerical data can only be filled using &quot;###&quot;, as it does not make
sense to round or truncate this data.

- Multiple table objects in the same float.  Each table float in the template LyX
file can only contain one table object.  If a float contains a second table object,
this table will not be filled.


######################
# Boldfacing entries
######################

It is straightforward to develop functions that conditionally write entries of
tables in boldface; functions may do so by inserting &#39;\series bold&#39; in the lines
of the filled LyX file immeadiately before phrases that the user wishes to make bold.
</pre></div>
</div>
</dd></dl>

<div class="toctree-wrapper compound">
</div>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="api/modify_dir/gslab_make.modify_dir.zip_dir.html" class="btn btn-neutral float-left" title="zip_dir" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="api/tablefill/gslab_make.tablefill.tablefill.html" class="btn btn-neutral float-right" title="tablefill" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2023, Matthew Gentzkow.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>